Skip to main content

AWSS3GetBucket

Type​

command

Summary​

Get a bucket description.

Syntax​

AWSS3GetBucket <pBucket>,<pParameters>,<pCallback>

Description​

The caller of this command will be sent the callback message on completion with two parameters:

  • the request ID
  • the response from the server parsed into an array.
  • an error message if one occurred

The array contains details about the bucket including objects it contains.

note

The message is sent before the tsNet connection is closed so it is possible to access the recieved headers using the tsNetRetrHeaders function

For futher details about this API see the AWS S3 REST API Documentation

Parameters​

NameTypeDescription

pBucket

The name of a bucket

pParameters

An array containing parameters to include in the request:

  • "delimiter" (optional string):A delimiter is a character you use to group keys. If you specify a prefix, all keys that contain the same string between the prefix and the first occurrence of the delimiter after the prefix are grouped under a single result element called CommonPrefixes. If you don't specify the prefix parameter, the substring starts at the beginning of the key. The keys that are grouped under the CommonPrefixes result element are not returned elsewhere in the response.
  • "encoding-type" (optional string): Requests Amazon S3 to encode the response and specifies the encoding method to use. An object key can contain any Unicode character. However, XML 1.0 parsers cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • "max-keys" (optional integer): Sets the maximum number of keys returned in the response body. If you want to retrieve fewer than the default 1,000 keys, you can add this to your request. The response might contain fewer keys, but it will never contain more. If there are additional keys that satisfy the search criteria, but these keys were not returned because max-keys was exceeded, the response contains IsTruncatedtrue/IsTruncated. To return the additional keys, see NextContinuationToken.
  • "prefix" (optional string): Limits the response to keys that begin with the specified prefix. You can use prefixes to separate a bucket into different groupings of keys. (You can think of using prefix to make groups in the same way you'd use a folder in a file system.)
  • "continuation-token" (optional string): When the Amazon S3 response to this API call is truncated (that is, IsTruncated response element value is true), the response also includes the NextContinuationToken element, the value of which you can use in the next request as the continuation-token to list the next set of objects. The continuation token is an opaque value that Amazon S3 understands. Amazon S3 lists objects in UTF-8 character encoding in lexicographical order.
  • "fetch-owner" (optional boolean): By default, the API does not return the Owner information in the response. If you want the owner information in the response, you can specify this parameter with the value set to true.
  • "start-after" (optional string): If you want the API to return key names after a specific object key in your key space, you can add this parameter. Amazon S3 lists objects in UTF-8 character encoding in lexicographical order. This parameter is valid only in your first request. In case the response is truncated, you can specify this parameter along with the continuation-token parameter, and then Amazon S3 will ignore this parameter.

pCallback

A command name to be sent on completion with the server reponse.

Examples​

local tParameters
put "/" into tParameters["delimiter"]
put "images/" into tParameters["prefix"]
AWSS3GetBucket "mybucket", tParameters, "getImagesFromBucketCallback"
put it into tRequestID

on getImagesFromBucketCallback pRequestID, pResult, pError
   if pError is empty then
      local tObjectKeys
      if isSeq(pResult["Contents"]) then
         repeat with tIndex = 1 to the number of elements of pResult["Contents"]
            put pResult["Contents"][tIndex]["Key"] & return after tObjectKeys
         end repeat
      else
         -- only one result
         put pResult["Contents"]["Key"] & return after tObjectKeys
      end if
   end if
end getImagesFromBucketCallback

function isSeq pSeq
   return item 2 of extents(pSeq) is the number of elements in pSeq
end isSeq

function: tsNetGetStatus, tsNetRetrHeaders

library: tsNet